home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / string.arc / STRINGS.DOC < prev    next >
Text File  |  1991-04-28  |  15KB  |  334 lines
  1.                        Turbo Pascal Rexx STRINGS Unit
  2.                     Version 1.1 for Turbo Pascal 5.0
  3.  
  4.       STRINGS.TPU is a Turbo Pascal unit containing 27 string-related
  5.       functions mostly implemented in assembler.  These routines are
  6.       highly optimized and make extensive use of the 80x86 string
  7.       oriented opcodes.  IBM mainframe hackers will notice that this
  8.       package, together with Turbo's built in string functions, is
  9.       substantially equivalent to the string routines available in IBM's
  10.       Rexx language.
  11.  
  12.                         Function Descriptions
  13.                         ---------------------
  14.  
  15. All functions are implemented in assembler, unless otherwise noted.
  16.  
  17. function left(str:string; width:byte; pad:char):string;
  18.          Returns STR left justified in a field of width WIDTH, padded out
  19.          with PAD characters.
  20.          Ex: left('hello',10,'=') returns 'hello====='
  21.              left('hello there',10,'=') returns 'hello ther'
  22.  
  23. function right(str:string; width:byte; pad:char):string;
  24.          Returns STR right justified in a field of width WIDTH, padded out
  25.          with PAD characters.
  26.          Ex: right('hello',10,'>') returns '>>>>>hello'
  27.              right('hello there',10,'>') returns 'ello there'
  28.  
  29. function center(str:string; width:byte; pad:char):string;
  30.          Returns STR centered in a string of length WIDTH, padded out
  31.          with PAD chars.
  32.          Ex: center('ABC',8,' ') returns '  ABC   '
  33.              center(' ABC ',8,'-') returns '- ABC --'
  34.              center('ABCDE',3,'-') returns 'ABC'
  35.  
  36. function strip(str:string; opt,ch:char):string;
  37.          Strips leading and/or trailing CH characters from STR.
  38.          Setting OPT to L, T or B causes leading, trailing, or both
  39.          leading and trailing characters to be stripped.
  40.          Ex: strip('   abcdef  ','L',' ') returns 'abcdef  '
  41.              strip('   abcdef  ','t',' ') returns '   abcdef'
  42.              strip('   abcdef  ','b',' ') returns 'abcdef'
  43.              strip('++ abcdef +','B','+') returns ' abcdef '
  44.  
  45. function lastpos(findstr,instr:string; start:byte):byte;
  46.          Returns the position of the last occurrance of FINDSTR in INSTR,
  47.          searching backwards from the character position START.  If START
  48.          is 0, the search begins at the end of INSTR.  Returns 0 if the
  49.          string is not found.
  50.          Ex: lastpos('he','he was the best',15) returns 9.
  51.              lastpos('he','he was the best',6) returns 1.
  52.              lastpos('he','he was the best',0) returns 9.
  53.              lastpos('he','he was the best',1) returns 0.
  54.  
  55. function firstpos(findstr,instr:string; start:byte):byte;
  56.          This function was included for completeness.  It works exactly
  57.          the same way as Turbo's built in POS function, except for the
  58.          presence of the START option.  It is equivalent to:
  59.          start-1+pos(findstr,copy(instr,start,length(instr)-start+1));
  60.          except for being more efficient.
  61.          Ex: firstpos('he','he was the best',15) returns 0.
  62.              firstpos('he','he was the best',6) returns 9.
  63.              firstpos('he','he was the best',0) returns 1.
  64.              firstpos('he','he was the best',1) returns 1.
  65.  
  66. function copies(str:string; count:byte):string;
  67.          Returns COUNT copies of STR concatenated together.
  68.          If the length of n(<=count) copies of STR would exceed 255,
  69.          n-1 copies are returned.
  70.          Ex:  copies('----+',4) returns '----+----+----+----+'
  71.  
  72. function overlay(new,str:string; pos:byte; pad:char):string;
  73.          Returns the string STR, overlayed by the string NEW, starting
  74.          at character position POS, padding out STR with PAD characters
  75.          if necessary.  If length(new)+pos>255, new is truncated to
  76.          protect the stack.
  77.          Ex: overlay('aygu','Ronald Reagan',9,'+') returns 'Ronald Raygun'
  78.              overlay('abc','xyz',6,'+') returns 'xyz++abc'
  79.  
  80. function uppercase(str:string):string;
  81.          Folds the argument STR to uppercase.
  82.          Ex: uppercase('abcdef123') returns 'ABCDEF123'
  83.  
  84. function lowercase(str:string):string;
  85.          Folds the argument STR to lowercase.
  86.          Ex: lowercase('ABCDEF123') returns 'abcdef123'
  87.  
  88. function words(str:string):byte;
  89.          Returns the number of (blank delimited) words in the string STR.
  90.          Ex: words('two four six      eight') returns 4.
  91.  
  92. function werd(str:string; n:byte):string;
  93.          Returns the N'th (blank delimited) word from the string STR.
  94.          The strange spelling is to avoid conflict with Tpas's WORD type.
  95.          Ex: werd('two     air is humin',3) returns 'is'
  96.              werd('two     air is humin',5) returns ''
  97.  
  98. function subword(str:string; n,count:byte):string;
  99.          Returns COUNT words from STR, starting at the N'th word.
  100.          Embedded blanks are preserved.
  101.          Ex: subword('one two three  four',2,3) returns 'two three  four'
  102.              subword('one two three  four',2,0) returns ''
  103.              subword('one two  three ',2,3) returns 'two  three'
  104.              subword('one two  three ',4,2) returns ''
  105.  
  106. function delword(str:string; n,count:byte):string;
  107.          Returns STR with COUNT words deleted, starting at word N.
  108.          Preceeding blanks are preserved.
  109.          Ex: delword('here   we go again',2,2) returns 'here   again'
  110.  
  111. function pos2word(str:string; pos:byte):byte;
  112.          Returns the number of the word in STR pointed to by POS.  If
  113.          POS points to a blank, the number of the following word is
  114.          returned.  If POS points after the last word or end of STR,
  115.          or POS is 0, then 0 is returned.
  116.          Ex: pos2word('abc def ghi ',4) returns 2.
  117.              pos2word('abc def ghi ',6) returns 2.
  118.              pos2word('abc def ghi ',11) returns 3.
  119.              pos2word('abc def ghi ',12) returns 0.
  120.              pos2word('abc def ghi ',0) returns 0.
  121.  
  122. function word2pos(str:string; wrd:byte):byte;
  123.          Returns the position in STR of the first character in the WRD'th
  124.          word.  If WRD>WORDS(STR) or WRD=0, returns 0.
  125.          Ex: word2pos('  abcd e  fghi jk',2) returns 8.
  126.          Note that this function is equivalent to Rexx's WORDINDEX
  127.          function.
  128.  
  129. function space(str:string; spc:byte):string;
  130.          Returns STR with each word separated by SPC blanks.
  131.          Ex: space('  here  we   go again  ',0) returns 'herewegoagain'
  132.              space('  here  we   go again  ',1) returns 'here we go again'
  133.  
  134. function translate(str,intable,outable:string):string;
  135.          Returns STR after translation via the map INTABLE->OUTABLE.
  136.          In other words, each occurrance in STR of the i'th character
  137.          in INTABLE is replaced by the i'th character in OUTABLE.
  138.          Ex: translate('ABC BDE',' BCF','XYZ ') returns 'AYZXYDE'
  139.          INTABLE and OUTABLE should be of the same length.
  140.  
  141. function verify(str,ref:string; opt:char; start:byte):byte;
  142.          Returns the position of the first character in STR (after START)
  143.          which matches/doesn't match a character in REF.  Setting OPT to
  144.          'M' or 'N' returns matching or non-matching character positions,
  145.          respectively.
  146.          Ex: verify('abcd1ef','0123456789','M',0) returns 5.
  147.              verify('123a125','0123456789','n',0) returns 4.
  148.  
  149. function compare(s1,s2:string):byte;
  150.          Compares S1 to S2 and returns the position of the first
  151.          characters which don't match, or 0 if all characters match.
  152.          Ex: compare('hello','hello there') returns 6.
  153.              compare('hello','hexlo') returns 3.
  154.              compare('hello','hello') returns 0.
  155.  
  156. function xrange(c1,c2:char):string;
  157.          Returns a string containing all characters from C1 to C2
  158.          inclusive.
  159.          Ex: xrange('a','h') returns 'abcdefgh'
  160.  
  161. function reverse(str:string):string;
  162.          Returns contents of STR in reverse order.
  163.          Ex: reverse(xrange('a','h')) returns 'hgfedcba'
  164.  
  165. function abbrev(str,abbr:string; len:byte):boolean;
  166.          Returns true if ABBR is an 'acceptable' abbreviation for STR.
  167.          The criterion is:
  168.             length(ABBR)>=LEN and ABBR=left(STR,length(ABBR),' ')
  169.          LEN should be set <= length(STR).
  170.          Ex: abbrev('DELETE','DEL',3)=true
  171.              abbrev('DELETE','DELY',3)=false
  172.              abbrev('DELETE','DELET',3)=true
  173.              abbrev('DELETE','DELETEX',3)=false
  174.  
  175. function d2x(i:word):xstr;
  176.          (XSTR is defined in the TPU as STRING[4])
  177.          Returns a four byte string equal to the hex representation of I.
  178.          Ex: d2x(255) returns '00FF'
  179.  
  180. function x2d(x:xstr):word;
  181.          Returns the numeric value represented by the xstr X.  Upper
  182.          and lower case A-F are valid on input.  No checking is done for
  183.          the validity of the characters in X, so garbage input gives
  184.          garbage output.  If the validity of X is in doubt, use the
  185.          VERIFY function first:
  186.          validx:=(verify(x,'0123456789ABCDEFabcdef','N')=0);
  187.          Ex: x2d('7F') returns 127.
  188.  
  189. The following functions are implemented in Pascal, utilizing one or more
  190. of the previous routines.
  191.  
  192. function justify(str:string; len:byte):string;
  193.          Distributes blanks between words in STR so that length(STR)=LEN.
  194.          If length(space(STR,1))>=LEN, justify just returns space(STR,1).
  195.          Ex: justify(' a  b cd  ef ',10)='a b  cd ef'
  196.  
  197. function chgstr(str:string; var old,new:string; n,count:byte):string;
  198.          Changes COUNT occurrances in STR of OLD to NEW, starting at
  199.          occurrance N.
  200.          Ex: chgstr('hello there','e','xx',2,1) returns 'hello thxxre'
  201.  
  202.                                    Usage Notes
  203.                                    -----------
  204.  
  205.       Note that Rexx's FIND and WORDLENGTH functions can be readily
  206.       synthesized using functions in this package:
  207.  
  208.       {find returns the number of the word in str1 where str2 starts}
  209.       find(str1,str2) ::= pos2word(str1,firstpos(str2,str1,0))
  210.  
  211.       {wordlength returns the length of a word in str}
  212.       wordlength(str,n) ::= length(word(str,n))
  213.  
  214. Why the lack of VAR string parameters? (in case you were wondering)
  215.  
  216.       I initially wrote this unit to use VAR string formal parameters in
  217.       the interest of speed, but I've since discovered that when calling
  218.       external assembler routines with value string formal parameters,
  219.       when the actual parameter is a string variable (as opposed to a
  220.       string expression), TP passes a pointer to the ACTUAL variable,
  221.       not a copy of the variable.  While this behavior isn't consistent
  222.       with the pascal standard, assembler isn't pascal, and it does give
  223.       the programmer the best of both worlds:  fast execution and low
  224.       stack overhead when using string variables as parameters, and the
  225.       flexibility of value parameters.  At any rate, string variable
  226.       function parameters are NEVER modified.
  227.  
  228. Differences between releases:
  229.  
  230. Release 1.05:
  231.  
  232.       Converted ABBREV and DELWORD to asm.  Included turbo compiler
  233.       directives {$N-,E-,D-,L-,B-,I-,R-,S+,V-} for optimization and
  234.       usage on non '87 machines.  Added PAD parameter to OVERLAY.  Added
  235.       CHGSTR.  Fixed bug in FIRSTPOS.  Changed behavior of SUBWORD when
  236.       COUNT=0, to match Rexx's SUBWORD function.
  237.  
  238. This release, 1.1:
  239.  
  240.       Compiled for Tpas 5.0.  Modified to cooperate with Tpas's dead
  241.       code elimination feature.  Added X2D & D2X.  Changed JUSTIFY to
  242.       use integer arithmetic for added speed.  Changed name of function
  243.       WORD to WERD to avoid conflict with Tpas's new WORD type.  Added
  244.       type XSTR for use with X2D & D2X.
  245.  
  246. Examples:
  247.  
  248.       Capitalize the first char in each word in a string S:
  249.       for i:=1 to words(S);
  250.           j:=word2pos(S,i);
  251.           S:=overlay(upcase(S[j]),S,j);
  252.       end;
  253.  
  254.       Find the lowest-ordered alphabetic character in a string STR
  255.       of uppercase characters:
  256.       lochar:=chr(ord('A')+verify(xrange('A','Z'),STR,'M',0)-1);
  257.  
  258.       Find the highest-ordered alphabetic character in a string STR
  259.       of uppercase characters:
  260.       hichar:=
  261.          chr(ord('Z')-verify(reverse(xrange('A','Z')),STR,'M',0)+1);
  262.  
  263.       Replace non-alphabetic chars with blanks in a string S:
  264.       S:=translate(S,xrange('!','9')+xrange(':','@')+
  265.              xrange('[','`')+xrange('{',''),left('',33,' '));
  266.       Or:
  267.       S:=translate(S,translate(xrange('!',''),xrange('A','Z')+xrange('a','z'),
  268.              left('',52,' ')),left('',ord('')-ord('!')+1,' '));
  269.  
  270.       Generate a sorted string S consisting of chars between '0' and 'z',
  271.       none of which occur in an alphanumeric string STR:
  272.       S:=space(translate(xrange('0','z'),STR,left('',length(STR),' ')),0);
  273.  
  274.       Generate a sorted string S, each of who's characters occurs at least
  275.       once in an alphanumeric string STR:
  276.       S:=space(translate(xrange('0','z'),translate(xrange('0','z'),
  277.              STR,left('',length(STR),' ')),left('',75,' ')),0);
  278.  
  279.       Permute the characters in a 'MM/DD/YY' date string to allow for
  280.       easy date comparison:
  281.       translate('78312645','12345678','12/25/88') returns '88/12/25'.
  282.  
  283.       A simple text formatting example is in txtfmt.pas.
  284.  
  285.  
  286.                              The Fine Print
  287.                              --------------
  288.  
  289.       STRINGS.TPU is copyright 1989 by Richard Winkel.  Asm & Pascal
  290.       source is available from me for $10 if you send me a formatted
  291.       360K disk in a stamped self addressed mailer.  If you want to
  292.       avoid the hassle, add $3 and I'll buy the floppy, mailer and
  293.       postage.
  294.  
  295. Send cash, check or money order to:
  296.  
  297.    Richard Winkel
  298.    Route 1, box 193
  299.    Harrisburg, MO.   65256
  300.  
  301. ------------------------------- cut here ---------------------------
  302.  
  303.                   Calling Syntax Guide to STRINGS.TPU
  304.  
  305. type xstr=string[4];
  306.  
  307. function abbrev(str,abbr:string; len:byte):boolean;
  308. function center(s:string; width:byte; pad:char):string;
  309. function chgstr(str,ostr,nstr:string; n,count:byte):string;
  310. function compare(s1,s2:string):byte;
  311. function copies(str:string; count:byte):string;
  312. function d2x(i:word):xstr;
  313. function delword(str:string; n,len:byte):string;
  314. function firstpos(findstr,instr:string; start:byte):byte;
  315. function justify(str:string; len:byte):string;
  316. function lastpos(findstr,instr:string; start:byte):byte;
  317. function left(str:string; width:byte; pad:char):string;
  318. function lowercase(s:string):string;
  319. function overlay(new,str:string; pos:byte; pad:char):string;
  320. function pos2word(s:string; pos:byte):byte;
  321. function reverse(str:string):string;
  322. function right(str:string; width:byte; pad:char):string;
  323. function space(str:string; spc:byte):string;
  324. function strip(s:string; opt,ch:char):string; {opt='L', 'T' or 'B'}
  325. function subword(str:string; num,count:byte):string;
  326. function translate(str,intable,outable:string):string;
  327. function uppercase(s:string):string;
  328. function verify(str,ref:string; opt:char; start:byte):byte; {opt='M' or 'N'}
  329. function werd(s:string;c:byte):string;
  330. function word2pos(s:string; wrd:byte):byte;
  331. function words(s:string):byte;
  332. function x2d(str:xstr):word;
  333. function xrange(c1,c2:char):string;
  334.